home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Applet.java < prev    next >
Text File  |  1998-09-22  |  16KB  |  449 lines
  1. /*
  2.  * @(#)Applet.java    1.43 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.applet;
  15.  
  16. import java.awt.*;
  17. import java.awt.image.ColorModel;
  18. import java.net.URL;
  19. import java.net.MalformedURLException;
  20. import java.util.Hashtable;
  21. import java.util.Locale;
  22.  
  23. /**
  24.  * An applet is a small program that is intended not to be run on 
  25.  * its own, but rather to be embedded inside another application. 
  26.  * <p>
  27.  * The <code>Applet</code> class must be the superclass of any 
  28.  * applet that is to be embedded in a Web page or viewed by the Java 
  29.  * Applet Viewer. The <code>Applet</code> class provides a standard 
  30.  * interface between applets and their environment. 
  31.  *
  32.  * @author      Arthur van Hoff
  33.  * @author      Chris Warth
  34.  * @version     1.43, 07/01/98
  35.  * @since       JDK1.0
  36.  */
  37. public class Applet extends Panel {
  38.     /**
  39.      * Applets can be serialized but the following conventions MUST be followed:
  40.      *
  41.      * Before Serialization:
  42.      * An applet must be in STOPPED state.
  43.      *
  44.      * After Deserialization:
  45.      * The applet will be restored in STOPPED state (and most clients will likely
  46.      *    move it into RUNNING state).
  47.      * The stub field will be restored by the reader.
  48.      */
  49.     transient private AppletStub stub;
  50.  
  51.     /**
  52.      * Sets this applet's stub. This is done automatically by the system. 
  53.      * 
  54.      * @param   stub   the new stub.
  55.      * @since   JDK1.0
  56.      */
  57.     public final void setStub(AppletStub stub) {
  58.     this.stub = (AppletStub)stub;
  59.     }
  60.  
  61.     /**
  62.      * Determines if this applet is active. An applet is marked active 
  63.      * just before its <code>start</code> method is called. It becomes 
  64.      * inactive immediately after its <code>stop</code> method is called. 
  65.      *
  66.      * @return  <code>true</code> if the applet is active;
  67.      *          <code>false</code> otherwise.
  68.      * @see     java.applet.Applet#start()
  69.      * @see     java.applet.Applet#stop()
  70.      * @since   JDK1.0
  71.      */
  72.     public boolean isActive() {
  73.     if (stub != null) {
  74.         return stub.isActive();
  75.     } else {    // If stub field not filled in, applet never active
  76.         return false;
  77.     }
  78.     }
  79.     
  80.     /**
  81.      * Gets the document URL. This is the URL of the document in which
  82.      * the applet is embedded.
  83.      *
  84.      * @return  the <a href="java.net.URL.html#_top_"><code>URL</code></a> of
  85.      *          the document that contains this applet.
  86.      * @see     java.applet.Applet#getCodeBase()
  87.      * @since   JDK1.0
  88.      */
  89.     public URL getDocumentBase() {
  90.     return stub.getDocumentBase();
  91.     }
  92.  
  93.     /**
  94.      * Gets the base URL. This is the URL of the applet itself. 
  95.      *
  96.      * @return  the <a href="java.net.URL.html#_top_"><code>URL</code></a> of
  97.      *          this applet.
  98.      * @see     java.applet.Applet#getDocumentBase()
  99.      * @since   JDK1.0
  100.      */
  101.     public URL getCodeBase() {
  102.     return stub.getCodeBase();
  103.     }
  104.  
  105.     /**
  106.      * Returns the value of the named parameter in the HTML tag. For 
  107.      * example, if this applet is specified as
  108.      * <ul><code>
  109.      *    <applet code="Clock" width=50 height=50><br>
  110.      *  <param name=Color value="blue"><br>
  111.      *  </applet>
  112.      * </code></ul>
  113.      * <p>
  114.      * then a call to <code>getParameter("Color")</code> returns the 
  115.      * value <code>"blue"</code>. 
  116.      * <p>
  117.      * The <code>name</code> argument is case insensitive. 
  118.      *
  119.      * @param   name   a parameter name.
  120.      * @return  the value of the named parameter.
  121.      * @since   JDK1.0
  122.      */
  123.      public String getParameter(String name) {
  124.      return stub.getParameter(name);
  125.      }
  126.  
  127.     /**
  128.      * Determines this applet's context, which allows the applet to 
  129.      * query and affect the environment in which it runs. 
  130.      * <p>
  131.      * This environment of an applet represents the document that 
  132.      * contains the applet. 
  133.      *
  134.      * @return  the applet's context.
  135.      * @since   JDK1.0
  136.      */
  137.     public AppletContext getAppletContext() {
  138.     return stub.getAppletContext();
  139.     }
  140.    
  141.     /**
  142.      * Requests that this applet be resized. 
  143.      *
  144.      * @param   width    the new requested width for the applet.
  145.      * @param   height   the new requested height for the applet.
  146.      * @since   JDK1.0
  147.      */
  148.     public void resize(int width, int height) {
  149.     Dimension d = size();
  150.     if ((d.width != width) || (d.height != height)) {
  151.         super.resize(width, height);
  152.         if (stub != null) {
  153.         stub.appletResize(width, height);
  154.         }
  155.     }
  156.     }
  157.  
  158.     /**
  159.      * Requests that this applet be resized. 
  160.      *
  161.      * @param   d   an object giving the new width and height.
  162.      * @since   JDK1.0
  163.      */    
  164.     public void resize(Dimension d) {
  165.     resize(d.width, d.height);
  166.     }
  167.  
  168.     /**
  169.      * Requests that the argument string be displayed in the 
  170.      * "status window". Many browsers and applet viewers 
  171.      * provide such a window, where the application can inform users of 
  172.      * its current state. 
  173.      *
  174.      * @param   msg   a string to display in the status window.
  175.      * @since   JDK1.0
  176.      */
  177.     public void showStatus(String msg) {
  178.     getAppletContext().showStatus(msg);
  179.     }
  180.  
  181.     /**
  182.      * Returns an <code>Image</code> object that can then be painted on 
  183.      * the screen. The <code>url</code> that is passed as an argument 
  184.      * must specify an absolute URL. 
  185.      * <p>
  186.      * This method always returns immediately, whether or not the image 
  187.      * exists. When this applet attempts to draw the image on the screen, 
  188.      * the data will be loaded. The graphics primitives that draw the 
  189.      * image will incrementally paint on the screen. 
  190.      *
  191.      * @param   url   an absolute URL giving the location of the image.
  192.      * @return  the image at the specified URL.
  193.      * @see     java.awt.Image
  194.      * @since   JDK1.0
  195.      */
  196.     public Image getImage(URL url) {
  197.     return getAppletContext().getImage(url);
  198.     }
  199.  
  200.     /**
  201.      * Returns an <code>Image</code> object that can then be painted on 
  202.      * the screen. The <code>url</code> argument must specify an absolute 
  203.      * URL. The <code>name</code> argument is a specifier that is 
  204.      * relative to the <code>url</code> argument. 
  205.      * <p>
  206.      * This method always returns immediately, whether or not the image 
  207.      * exists. When this applet attempts to draw the image on the screen, 
  208.      * the data will be loaded. The graphics primitives that draw the 
  209.      * image will incrementally paint on the screen. 
  210.      *
  211.      * @param   url    an absolute URL giving the base location of the image.
  212.      * @param   name   the location of the image, relative to the
  213.      *                 <code>url</code> argument.
  214.      * @return  the image at the specified URL.
  215.      * @see     java.awt.Image
  216.      * @since   JDK1.0
  217.      */
  218.     public Image getImage(URL url, String name) {
  219.     try {
  220.         return getImage(new URL(url, name));
  221.     } catch (MalformedURLException e) {
  222.         return null;
  223.     }
  224.     }
  225.  
  226.     /**
  227.      * Returns the <code>AudioClip</code> object specified by the 
  228.      * <code>URL</code> argument. 
  229.      * <p>
  230.      * This method always returns immediately, whether or not the audio 
  231.      * clip exists. When this applet attempts to play the audio clip, the 
  232.      * data will be loaded. 
  233.      *
  234.      * @param   url  an absolute URL giving the location of the audio clip.
  235.      * @return  the audio clip at the specified URL.
  236.      * @see     java.applet.AudioClip
  237.      * @since   JDK1.0
  238.      */
  239.     public AudioClip getAudioClip(URL url) {
  240.     return getAppletContext().getAudioClip(url);
  241.     }
  242.  
  243.     /**
  244.      * Returns the <code>AudioClip</code> object specified by the 
  245.      * <code>URL</code> and <code>name</code> arguments. 
  246.      * <p>
  247.      * This method always returns immediately, whether or not the audio 
  248.      * clip exists. When this applet attempts to play the audio clip, the 
  249.      * data will be loaded. 
  250.      * 
  251.      * @param   url    an absolute URL giving the base location of the
  252.      *                 audio clip.
  253.      * @param   name   the location of the audio clip, relative to the
  254.      *                 <code>url</code> argument.
  255.      * @return  the audio clip at the specified URL.
  256.      * @see     java.applet.AudioClip
  257.      * @since   JDK1.0
  258.      */
  259.     public AudioClip getAudioClip(URL url, String name) {
  260.     try {
  261.         return getAudioClip(new URL(url, name));
  262.     } catch (MalformedURLException e) {
  263.         return null;
  264.     }
  265.     }
  266.  
  267.     /**
  268.      * Returns information about this applet. An applet should override 
  269.      * this method to return a <code>String</code> containing information 
  270.      * about the author, version, and copyright of the applet. 
  271.      * <p>
  272.      * The implementation of this method provided by the 
  273.      * <code>Applet</code> class returns <code>null</code>. 
  274.      *
  275.      * @return  a string containing information about the author, version, and
  276.      *          copyright of the applet.
  277.      * @since   JDK1.0
  278.      */
  279.     public String getAppletInfo() {
  280.     return null;
  281.     }
  282.  
  283.     /** 
  284.      * Gets the Locale for the applet, if it has been set.
  285.      * If no Locale has been set, then the default Locale 
  286.      * is returned.
  287.      *
  288.      * @return  [Needs to be documented!]
  289.      * @since   JDK1.1
  290.      */
  291.  
  292.     public Locale getLocale() {
  293.       Locale locale = super.getLocale();
  294.       if (locale == null) {
  295.     return Locale.getDefault();
  296.       }
  297.       return locale;
  298.     }
  299.  
  300.     /**
  301.      * Returns information about the parameters than are understood by 
  302.      * this applet. An applet should override this method to return an 
  303.      * array of <code>Strings</code> describing these parameters. 
  304.      * <p>
  305.      * Each element of the array should be a set of three 
  306.      * <code>Strings</code> containing the name, the type, and a 
  307.      * description. For example:
  308.      * <p><blockquote><pre>
  309.      * String pinfo[][] = {
  310.      *     {"fps",    "1-10",    "frames per second"},
  311.      *     {"repeat", "boolean", "repeat image loop"},
  312.      *     {"imgs",   "url",     "images directory"}
  313.      * };
  314.      * </pre></blockquote>
  315.      * <p>
  316.      * The implementation of this method provided by the 
  317.      * <code>Applet</code> class returns <code>null</code>. 
  318.      *
  319.      * @return  an array describing the parameters this applet looks for.
  320.      * @since   JDK1.0
  321.      */
  322.     public String[][] getParameterInfo() {
  323.     return null;
  324.     }
  325.  
  326.     /**
  327.      * Plays the audio clip at the specified absolute URL. Nothing 
  328.      * happens if the audio clip cannot be found. 
  329.      *
  330.      * @param   url   an absolute URL giving the location of the audio clip.
  331.      * @since   JDK1.0
  332.      */
  333.     public void play(URL url) {
  334.     AudioClip clip = getAudioClip(url);
  335.     if (clip != null) {
  336.         clip.play();
  337.     }
  338.     }
  339.  
  340.     /**
  341.      * Plays the audio clip given the URL and a specifier that is 
  342.      * relative to it. Nothing happens if the audio clip cannot be found. 
  343.      *
  344.      * @param   url    an absolute URL giving the base location of the
  345.      *                 audio clip.
  346.      * @param   name   the location of the audio clip, relative to the
  347.      *                 <code>url</code> argument.
  348.      * @since   JDK1.0
  349.      */
  350.     public void play(URL url, String name) {
  351.     AudioClip clip = getAudioClip(url, name);
  352.     if (clip != null) {
  353.         clip.play();
  354.     }
  355.     }
  356.  
  357.     /**
  358.      * Called by the browser or applet viewer to inform 
  359.      * this applet that it has been loaded into the system. It is always 
  360.      * called before the first time that the <code>start</code> method is 
  361.      * called. 
  362.      * <p>
  363.      * A subclass of <code>Applet</code> should override this method if 
  364.      * it has initialization to perform. For example, an applet with 
  365.      * threads would use the <code>init</code> method to create the 
  366.      * threads and the <code>destroy</code> method to kill them. 
  367.      * <p>
  368.      * The implementation of this method provided by the 
  369.      * <code>Applet</code> class does nothing. 
  370.      *
  371.      * @see     java.applet.Applet#destroy()
  372.      * @see     java.applet.Applet#start()
  373.      * @see     java.applet.Applet#stop()
  374.      * @since   JDK1.0
  375.      */
  376.     public void init() {
  377.     }
  378.  
  379.     /**
  380.      * Called by the browser or applet viewer to inform 
  381.      * this applet that it should start its execution. It is called after 
  382.      * the <code>init</code> method and each time the applet is revisited 
  383.      * in a Web page. 
  384.      * <p>
  385.      * A subclass of <code>Applet</code> should override this method if 
  386.      * it has any operation that it wants to perform each time the Web 
  387.      * page containing it is visited. For example, an applet with 
  388.      * animation might want to use the <code>start</code> method to 
  389.      * resume animation, and the <code>stop</code> method to suspend the 
  390.      * animation. 
  391.      * <p>
  392.      * The implementation of this method provided by the 
  393.      * <code>Applet</code> class does nothing. 
  394.      *
  395.      * @see     java.applet.Applet#destroy()
  396.      * @see     java.applet.Applet#init()
  397.      * @see     java.applet.Applet#stop()
  398.      * @since   JDK1.0
  399.      */
  400.     public void start() {
  401.     }
  402.  
  403.     /**
  404.      * Called by the browser or applet viewer to inform 
  405.      * this applet that it should stop its execution. It is called when 
  406.      * the Web page that contains this applet has been replaced by 
  407.      * another page, and also just before the applet is to be destroyed. 
  408.      * <p>
  409.      * A subclass of <code>Applet</code> should override this method if 
  410.      * it has any operation that it wants to perform each time the Web 
  411.      * page containing it is no longer visible. For example, an applet 
  412.      * with animation might want to use the <code>start</code> method to 
  413.      * resume animation, and the <code>stop</code> method to suspend the 
  414.      * animation. 
  415.      * <p>
  416.      * The implementation of this method provided by the 
  417.      * <code>Applet</code> class does nothing. 
  418.      *
  419.      * @see     java.applet.Applet#destroy()
  420.      * @see     java.applet.Applet#init()
  421.      * @since   JDK1.0
  422.      */
  423.     public void stop() {
  424.     }
  425.  
  426.     /**
  427.      * Called by the browser or applet viewer to inform 
  428.      * this applet that it is being reclaimed and that it should destroy 
  429.      * any resources that it has allocated. The <code>stop</code> method 
  430.      * will always be called before <code>destroy</code>. 
  431.      * <p>
  432.      * A subclass of <code>Applet</code> should override this method if 
  433.      * it has any operation that it wants to perform before it is 
  434.      * destroyed. For example, an applet with threads would use the 
  435.      * <code>init</code> method to create the threads and the 
  436.      * <code>destroy</code> method to kill them. 
  437.      * <p>
  438.      * The implementation of this method provided by the 
  439.      * <code>Applet</code> class does nothing. 
  440.      *
  441.      * @see     java.applet.Applet#init()
  442.      * @see     java.applet.Applet#start()
  443.      * @see     java.applet.Applet#stop()
  444.      * @since   JDK1.0
  445.      */
  446.     public void destroy() {
  447.     }
  448. }
  449.